improve liststore docs

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 3189d5ee93c2d9c2c746fdf83870e90506be90e4..e2635b8a342ee3f9c2a4adc479492b905124f02f 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+2006-02-10  Matthias Clasen  <mclasen@redhat.com>
+
+       * gtk/tmpl/gtkliststore.sgml: Add a section about
+       atomicity of insertions. (#329831, Milosz Derezynski)
+
 2006-02-03  Matthias Clasen  <mclasen@redhat.com>
 
        * gtk/tmpl/gtkmenushell.sgml: 

diff --git a/docs/reference/gtk/tmpl/gtkliststore.sgml b/docs/reference/gtk/tmpl/gtkliststore.sgml
index ebebf7421e9c9e6c3a2bcd0e8485a6e3773bf03b..29db5a45f916800b10398d0605a91af762fc0bc8 100644 (file)
--- a/docs/reference/gtk/tmpl/gtkliststore.sgml
+++ b/docs/reference/gtk/tmpl/gtkliststore.sgml
@@ -91,6 +91,19 @@ that #GtkTreeIter<!-- -->s can be cached while the row exists.  Thus, if
 access to a particular row is needed often and your code is expected to
 run on older versions of GTK+, it is worth keeping the iter around.
 </para>
+<title>Atomic Operations</title>
+<para>
+It is important to note that only the methods @gtk_list_store_insert_with_values and
+@gtk_list_store_insert_with_valuesv are atomic, in the sense that the row is being appended
+to the store and the values filled in in a single operation with regard to #GtkTreeModel signaling.
+In contrast, using e.g. @gtk_list_store_append and then @gtk_list_store_set will first create a row,
+which triggers the "row_inserted" #GtkTreeModel signal on #GtkListStore. The row, however, is still
+empty, and any signal handler connecting to "row_inserted" on this particular store should be prepared
+for the situation that the row might be empty.
+This is especially important if you are wrapping the #GtkListStore inside a #GtkTreeModelFilter and are
+using a #GtkTreeModelFilterVisibleFunc. Using any of the non-atomic operations to append rows to the #GtkListStore
+will cause the #GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the function must be prepared for that.
+</para>
 </refsect2>
 
 <!-- ##### SECTION See_Also ##### -->